Related Issues

• fixes Add missing operations to the ArcadeDBDocumentStore #2980

Proposed Changes:

Implements five metadata query methods for ArcadeDBDocumentStore listed in issue #2980:

• count_documents_by_filter
• count_unique_metadata_by_filter
• get_metadata_fields_info
• get_metadata_field_min_max
• get_metadata_field_unique_values

Also adds:

• _infer_metadata_field_type & _extract_distinct_values static helpers.
• SCHEMA_SAMPLING_LIMIT class constant (default 1000)

Implementation notes

Schema sampling: get_metadata_fields_info uses LIMIT 1000 via SCHEMA_SAMPLING_LIMIT to prevent the OOM risks and latency issues associated with full-table scans on large stores.

Search term embedding : get_metadata_field_unique_values embeds the search term via _sql_str() rather than positional_params. This is because _command currently sends params as a JSON array, but ArcadeDB's HTTP API
expects a named params map {"key": value} with :key placeholders. No existing method uses positional_params, so this has not caused failures elsewhere.

How did you test it?

Integration tests added for all five methods covering: happy path, no matches, empty filter, empty field list, pagination, and case-insensitive search. All run against real ArcadeDB via the existing Docker service in CI.
Bug Fix: Resolved a FrozenInstanceError in assert_documents_are_equal using dataclasses.replace for document comparison.

hatch run fmt-check        
hatch run test:types       
hatch run test:integration 

Known follow-up items

• _command positional_params sends a JSON array, but ArcadeDB expects a named map. Will raise as a separate bug issue after further verification.
• AstraDocumentStore._get_metadata_projection_documents fetches all documents with no limit for schema inference. Will raise as an enhancement for Astra after further verification.

Notes for the reviewer

SQL Constraints: Used SELECT DISTINCT + Python len() for unique counts because the current ArcadeDB SQL parser has limitations with COUNT(DISTINCT ...).
Sampling Default: 1000 is the current default for schema inference; let me know if the team prefers a different threshold.

AI assistance disclaimer

Developed with AI assistance for syntax review and code audit. I authored the underlying logic, verified all implementations against the ArcadeDB HTTP API, and confirmed all tests pass locally.

Checklist

• I have read the contributors guidelines and the code of conduct
• I have updated the related issue with new insights and changes
• I added unit tests and updated the docstrings
• I've used one of the conventional commit types for my PR title: fix:, feat:, build:, chore:, ci:, docs:, style:, refactor:, perf:, test:.